
                  -----------------------------            
                          MOCHA TN3270 

                           USER GUIDE

                          Version 1.00
             
                  -----------------------------            

Contents
========

1.0 Product Overview
1.1   Functionality
1.2   Connect
1.3   Function keys
1.4   Status line
1.5   Focus

2.0 Modes 
2.1   Java Application 
2.2   Java Applet 
2.3   Java pop-up Applet

3.0 Limitations 
3.1   Which hosts to connect
3.2   Control the size and position of pop-up windows
3.3   Known Restrictions

4.0 Parameters
4.1   Configuration file
4.2   HTML page
4.3   Parameter type 
4.4   Parameter keyfile 
4.5   Parameter license 
4.6   Parameter license_key 
4.7   Parameter negotiate
4.8   Parameter keyboard_bar
4.9   Parameter unprotected_show 
4.10  Parameter color_bg
4.11  Parameter color_unprotected
4.12  Parameter color_cursor
4.13  Parameter page_color
4.14  Parameters screen_width and screen_height
4.15  Parameters screen_x and screen_y
4.16  Parameters host and port
4.17  Parameter auto_stop
4.18  Parameter termtype
4.19  Parameter alternate 
4.20  parameter debug
4.21  parameters proxy_host, proxy_port and proxy_syntax
4.22  parameter ebcdic_file
4.23  parameters color_XXXX

5.0 Keyboard mapping
5.1   Default keyboard

6.0 ASCII - EBCDIC tables
6.1   File tn3270.ebc
6.2   File tn3270.dan

7.0 License System

8.0 Files 

1.0 Product overview
================
Mocha TN3270 is an TN3270 emulator written in java, which makes it possible
from a java enabled browser, as Microsoft Internet Explorer or Netscape 
Navigator, to connect an IBM Mainframe, which supports TN3270.

1.1 Functionality
=================
 - Supports Extended Field Attributes 
 - Alternate screen size (24x80 or 32x80)
 - Unprotected fields can be shown in a different color
 - User defined color values
 - Layout as a Windows'95 application.. 
 - Pop down menu's
 - Keyboard mapping help window
 - Automatic resize of applet window
 - User defined keyboard layout
 - Functions keys can also be shown as push buttons.
 - Many trim parameters. 
 - Can run either as
     - Java Application.
     - Applet.
     - Applet pop-up window. 

1.2 Connect
===========
It is possible to connect to a host from the File menu. A pop-up window is 
shown. Enter a host name and a port number . The port number for TN3270 is 
default 23. How to use a proxy host, see parameter proxy_host, 4.21. 
If the name service is not running correct or the host does not response, some 
workstations can hang for a minute or more. Mocha TN3270 can do nothing about
it. It is not possible to cancel a started request in the current version
of Java.

1.3 Function keys
=================
As the layout of a Java keyboard is different from a 3270  keyboard, some
changes has been necessary.

- Function keys F1 to F12 can be pressed either in normal, shifted or 
  ctrl mode.
- PF1 - PF24, PA1, PA2, PA3, INSERT, CLEAR, DUP and FM can be pressed 
  with the mouse.
- Key F10 is controlled from some browsers, meaning if key F10 is pressed
  the browser takes control, and Mocha TN3270 lose its focus for the keyboard.
- Ins/Insert keys on the pc-keyboard cannot be used.

See chapter 5 for a description of how to use and define function keys

1.4 Status line
===============
Last line in the applet shows, as on a real IBM 3270 screen the status of
the session. The layout is:

-------------------------------------------------------------------------
  TN    <line state>   <session state>      <insert mode>  <last key>
-------------------------------------------------------------------------

TN         : Connected to a host supporting the TN3270 protocol

Line state :
             REQUEST : Mocha Tn3270 asks host for a connection
             ONLINE  : Connection has been established
             OFFLINE : No connection

Session state:

             X-WAIT  : a request has been send to the host, and the
                       user must wait on a response. RESET key (ESC) can
                       clear this state.

             X-WRONG INPUT : 
                       User enters data which is not legal. As an
                       example if the cursor is not placed on an 
                       input field. If non numeric data is entered in a 
                       numeric field the text "(numeric)" is added to
                       X-WRONG INPUT. 
                       Move the cursor or press RESET, to release the error 
                       situation. On a real 3270 screen, the user must 
                       press the RESET key.

Insert mode: INSERT:   data is inserted at the cursor position, and characters
                       after the cursor moves to the right.
                       Use the INSERT key (not Insert on the pc keyboard!)
                       to select/release this option.

Last key:              Shows last function key pressed:
                       PF1 - PF24, ENTER, CLEAR ,PA1 PA2 or PA3.
 
1.5 Focus
=========
As with normal Microsoft windows the title bar of the window will have
the color blue when in focus and gray when not in focus.

2.0 Modes
=========
It is possible to start Mocha TN3270 in different layout modes.
The mode number will be used in chapter 4, (parameters) to indicate when 
the parameter is valid.
The most useful mode will in most cases be mode 2 (applet).


2.1 Java Application - mode 1
=============================
It is possible to start Mocha TN3270 direct with an interpreter. It can be 
useful in some configurations, as a pure NC environment. If the interpreter
is named java the syntax is:

  java tn3270exe <host> [<configuration file>]

where 

  host                : name of the IBM Mainframe to connect.
  configuration file  : name of configuration file. If omitted tn3270.cfg
                        will be used.

Mocha TN3270 will pop up as a window frame, which is movable, and also can
be scaled on the page.

2.2 Java Applet - mode 2
========================
Mocha TN3270 is started as part of a HTML page. It will have a fixed 
position and size. 

2.3 Java pop-up Applet - mode 3
===============================
As mode 2 but Mocha TN3270 runs as a window frame, which is movable, and 
also can be scaled on the page. A Warning message will be displayed at 
the bottom of the window. Microsoft Internet Explorer shows : 
"Warning: Applet Window"

3.0 Limitations
===============
As to the strict security issue for java applets there is some limitations
on the functionality for Mocha TN3270.

3.1 Which hosts to connect
==========================
It is only possible to create a connection on the host, from where the applet 
has been downloaded. This limitation is build into the browser.
It is possible to install a proxy server on the host, which could route the 
TN3270 request to another host. A better solution is to install Mocha TN3270
on all the hosts, to which the workstation wants to connect.

3.2 Control the size and position of pop-up windows
=================================================
Some browsers does not give the possibility for an applet to define where and 
the size of a window applet. Therefore the parameters screen_width/
screen_height and screen_x/screen_y could give less meaning in some cases.

3.3 Known Restrictions
======================
The following 3270 elements have not been implemented:

  - blinking
  - programmed symbols
  - sound alarm
  - light pen
  - file transfer (IND$FILE)
 
4.0 Parameters
==============
Parameters to Mocha TN3270 is given in a file if running in mode 1
(application), and in mode 2 and 3 as parameters in HTML format.

Following syntax is used in this chapter: 

 <text>      : don't include < > as part of the parameter
 text1|text2 : use either text1 or text2

4.1 Configuration file
================================
The configuration file is as default named tn3270.cfg. The syntax is:

# This is a comment line
name=value

Example of a simple file:

  #Configuration file for Mocha TN3270
  color_cursor=#203048    
  keyboard_bar=true
  keyfile=keys.new

The different types of names are given in chapter 4.3 - 4.23.

4.2 HTML page
=========================
An applet is defined in a HTML page with label <APPLET>. See other source of 
information for how to write HTML.

An example of a HTML page:

<HTML>
<HEAD>
<TITLE> Mocha TN3270 example </TITLE>
</HEAD>
<BODY>
<APPLET CODE="tn3270.class" WIDTH=700 HEIGHT=500>
<param name=host value="ibm">
<param name=port value="23">
<param name=color_cursor value="#203047">
<param name=keyboard_bar value="true">
<param name=type value="applet">
</APPLET>
</BODY>
</HTML>

CODE parameter must always be "tn3270.class". It is the name of the master file
for the binary Mocha TN3270 product.
WIDTH and HEIGHT gives the size of the applet. If running in mode 3 as a 
pop-up window, state the WIDTH and HEIGHT to 1. 

Just as for the configuration file in chapter 4.1, each parameter is build of
a name and a value. In the example above parameter host is given value ibm.
It is very important to remember <> around each line, and the value must be 
surrounded with "".

4.3 Parameter type (mode 2,3)
===============================
gives the type of the applet. A pop-up window or an "normal" applet.

Syntax:

  name=applet value="frame|applet"

  Frame is a pop-up window.

4.4 Parameter keyfile (mode 1,2,3)
===============================
Keyboard mapping between pc-key board and 3270 keyboard are defined in
a file with default name "keys". With this parameter another file can be used.

Syntax:

  name=keyfile value="<a file name>"

4.5 Parameter license (mode 1,2,3)
===============================
Name of the company using Mocha TN3270. Should only be included together 
with parameter "license_key".

SYNTAX:

  name=license value="<name of a company>" 
 
4.6 Parameter license_key (mode 1,2,3)
===============================
When ordering Mocha TN3270, an encrypted license code will be received. Use
this together with parameter "license" to clear the DEMO warning in the
title line.

SYNTAX:

  name=license_key value="<encrypted key>"
 
4.7 Parameter negotiate (mode 1,2,3)
====================================
When a TN3270 session is created to a host, a negotiation takes place, where 
the setup of endpoints is agreed on. If this parameter is used, the negotiation
will be displayed.

SYNTAX:

  name=negotiate value="true|false"

Default is false.

4.8 Parameter keyboard_bar (mode 1,2,3)
========================================
Defines if function keys PF1 - PF24 + other keys should be displayed as buttons.

SYNTAX:

 name=keyboard_bar value="true|false"

Default is true.

4.9 Parameter unprotected_show (mode 1,2,3)
===========================================
Defines if unprotected fields (input fields) should be displayed in 
another color than the background color.

SYNTAX:

 name=unprotected_show value="true|false"

Default is false.

4.10 Parameter color_bg (mode 1,2,3)
====================================
The color of the background can be defined with this parameter.

SYNTAX:

  name=color_bg value="#rrggbb"

where rr is red color in hex (0-FF).
      gg is green color in hex (0-FF).
      bb is blue color in hex (0-FF).

The syntax is the same as used in the HTML language.

Example:

  name=color_bg value="#20f030"

4.11 Parameter color_unprotected (mode 1,2,3)
=============================================
If parameter "unprotected_show" is enabled, this parameter defines
the color for the background of unprotected fields. This parameter
can also be trimmed from the menu.

SYNTAX:

  name=color_unprotected value="#rrggbb"

where rr is red color in hex (0-FF).
      gg is green color in hex (0-FF).
      bb is blue color in hex (0-FF).

The syntax is the same as used in the HTML language.

4.12 Parameter color_cursor (mode 1,2,3)
========================================
The color of the cursor can be defined with this parameter.

SYNTAX:

  name=color_cursor value="#rrggbb"

where rr is red color in hex (0-FF).
      gg is green color in hex (0-FF).
      bb is blue color in hex (0-FF).

The syntax is the same as used in the HTML language.

4.13 Parameter page_color (mode 2)
==================================
When Mocha TN3270 is loaded as an applet, it will resize to use the largest 
possible font given the size of the applet. As browsers and screen solutions
vary between different workstations there will always be some space left around
the Mocha TN3270 applet which cannot be used. 
This parameter defines the color of this space and it should be set to the 
color of the HTML page.

SYNTAX:

  name=page_color value="#rrggbb"

where rr is red color in hex (0-FF).
      gg is green color in hex (0-FF).
      bb is blue color in hex (0-FF).

The syntax is the same as used in the HTML language.
 
4.14 Parameters screen_width and screen_height (mode 1,3)
=========================================================
If started as a frame window, these parameters defines the size of the window 
in pixels.

SYNTAX:

  name=screen_width value=<number>
  name=screen_height value=<number>

Default is 600 x 600. 
 
4.15 Parameters screen_x and screen_y (mode 1,3)
================================================
If started as a frame window, these parameters defines the upper left corner
of the window in pixels.

SYNTAX:

  name=screen_x value=<number>
  name=screen_y value=<number>

Default is 100,75. 

4.16 Parameters host and port (mode 2,3)
================================================
These parameters defines which host to connect, when the applet is loaded.
The default port number for TN3270 is 23. 

SYNTAX:

  name=host value=<a host name>
  name=port value=<number>

Default port is 23. The host name can either be a name or an Internet
address as 198.66.23.11

4.17 Parameter auto_stop (mode 2,3)
================================================
Auto_stop selects if a TN3270 session should terminate when the
user select another HTML page
 
SYNTAX:

  name=auto_stop value=<true|false>

Default is true

4.18 Parameter termtype (mode 1,2,3)
================================================
The termtype is send to the host in the login phase. It defines the type
of terminal supported.

   IBM-3278-2-E   : Model 2 screen size 24*80
   IBM-3278-3-E   : Model 3 screen size 32*80
 
SYNTAX:

  name=termtype value=<type of terminal emulation>

Default is IBM-3278-2-E

4.19 Parameter alternate (mode 1,2,3)
================================================
The application on the IBM host can request for an alternate screen
size. This parameter defines the size. Normally this parameter should
follow the name define in termtype (4.19).
 
SYNTAX:

  name=alternate value=<24 or 32>

Default is 32
 
4.20 Parameter debug (mode 1)
================================================
It is possible to copy all data coming from the host to a file.
This file can be used later for debug purpose. The name of the file
is always "trace". As to security, this parameter will only work in mode 1.
 
SYNTAX:

  name=debug value=<true|false>

Default is false

4.21 Parameters proxy_host, proxy_port and proxy_syntax (mode 1,2,3) 
====================================================================
It is possible to use a TN3270 proxy host as gateway to other hosts. Mocha
TN3270 will connect to the proxy host, and issue a new connect sequence.
 
SYNTAX:

  name=proxy_host value=<proxy host name>
  name=proxy_port value=<proxy port number>
  name=proxy_syntax value=<syntax>
   
proxy_syntax defines how to format the connect sequence send to the
proxy host. 

  $1 = proxy_host
  $2 = proxy_port
  \abc = octal value. (LF = \012 and CR = \015)

Example: 

  name=proxy_host value=myproxy
  name=proxy_port value=911
  name=host value=wintermute
  name=port value=23
  name=proxy_syntax value=\012Connnect $1:$2\015\012

  Mocha TN3270 will connect to myproxy port 911, and send the connect
  sequence: <LF>Connect wintermute:23<CR><LF>
 
It is also possible to enter the login sequence to the proxy host from
the keyboard. Just define the value of proxy_syntax as "\015" or " ".

4.22 Parameter ebcdic_file (mode 1,2,3)
================================================
It is possible to define which EBCDIC <--> ascii table to use.
 
SYNTAX:

  name=ebcdic_file value=<file name>

Default is tn3270.ebc

4.23 Parameter color_XXXX (mode 1,2,3)
====================================
It is possible to change the default colors. 3270 uses the colors as:

green    : unprotected normal intensity
red      : unprotected intensified
blue     : protected, normal intensity
white    : protected, intensified

Modern applications can use extended attributes, which gives even more 
colors.

SYNTAX:

  name=color_blue value="#rrggbb"
  name=color_green value="#rrggbb"
  name=color_white value="#rrggbb"
  name=color_red value="#rrggbb"
  name=color_yellow value="#rrggbb"
  name=color_ping value="#rrggbb"
  name=color_turquoise value="#rrggbb"       

where rr is red color in hex (0-FF).
      gg is green color in hex (0-FF).
      bb is blue color in hex (0-FF).

The syntax is the same as used in the HTML language.

Example:

  name=color_blue value="#1000ff"

5.0 Keyboard mapping
====================
As it is individual how to map the keyboard, all function keys has
been made changeable.

The default configuration file is named "keys", and should exist in the same 
catalog as the *.class files of Mocha TN3270. 

Syntax for file "keys":

  Comments starts with #
  <pc-key> <3270 key>

  The pc-key's are
    
    fxx  : xx is 1 .. 12 (function key f1 - f12)
    Fxx  : xx is 1 .. 12 (shift + function key f1 - f12)
    cfxx : xx is 1 .. 12 (ctrl + function key f1 - f12)
    CFxx : xx is 1 .. 12 (shift + ctrl + function key f1 - f12)
    HOME
    END
    PGUP
    PGDN
    ESC
    RETURN

  The 3270 keys are:

    PF1 - PF24
    INSERT
    ERASEF     (erase current field)
    ERASEINPUT (erase all input fields)
    CLEAR      (clear the screen, and inform the host about it)
    STARTF     (go to start of current field)
    ENDF       (go to end of current field)
    BTAB       (go to previous field) (normal shift TAB will also work)
    TAB        (go to next field) (normal TAB key will also work)
    NL         (go to first field on next line)
    RESET      (reset keyboard)
    ENTER       

Example of a "keys" file:

# TN3270  keymap
#     
# <pc - key>  <3270 key> 
f1   PF1
f2   PF2
cf5  INSERT
cf6  ERASEF
cf7  ERASEINPUT
cf8  CLEAR
..

5.1 Default keyboard
====================
The default file "keys", contains following mapping of the keyboard:

  pc-Key       3270-key       pc-key              3270-key  
-----------------------      -----------------------------    
  f1              PF1          crtl f1              PA1          
  f2              PF2          ctrl f2              PA2          
  f3              PF3          ctrl f3              PA3          
  f4              PF4          ctrl f4              -            
  f5              PF5          ctrl f5              INSERT       
  f6              PF6          ctrl f6              ERASE FIELD  
  f7              PF7          ctrl f7              ERASE INPUT  
  f8              PF8          ctrl f8              CLEAR        
  f9              PF9          ctrl f9              -
  f10             PF10         ctrl f10             -
  f11             PF11         ctrl f11             PF10        
  f12             PF12         ctrl f12             PF22        
                                                 
  pc-Key       3270-key       pc-key              3270-key  
-----------------------      -----------------------------    
  shift f1        PF13         crtl shift f1        -         
  shift f2        PF14         ctrl shift f2        -         
  shift f3        PF15         ctrl shift f3        -         
  shift f4        PF16         ctrl shift f4        -         
  shift f5        PF17         ctrl shift f5        -          
  shift f6        PF18         ctrl shift f6        -         
  shift f7        PF19         ctrl shift f7        -         
  shift f8        PF20         ctrl shift f8        -         
  shift f9        PF21         ctrl shift f9        -         
  shift f10       PF22         ctrl shift f10       -        
  shift f11       PF23         ctrl shift f11       -        
  shift f12       PF24         ctrl shift f12       -        

 '-' is not used.

  pc-Key       3270-key    
------------------------
  HOME         GOTO START FIELD
  END          GOTO END OF FIELD
  PGUP         BACK TAB
  PGDN         TAB
  ESC          RESET KEYBOARD

6.0 ASCII - EBCDIC tables
=========================
As IBM hosts uses different codepages, it is not possible to include
all possible types of layout in Mocha TN3270. 
File tn3270.ebc contains an ascii - EBCDIC table which will work in most
cases. If national characters are used, it is necessary to change this file.
It can be done with any ascii editor.

The syntax of the file is :

# This is a comment
<ebcdic value>  <ascii value>

Example:

 # part of a file
 40 20
 81 a
 82 b
 83 c
 84 d

Remark it is possible to write ASCII value either as a 2 digit hex number
or an ASCII character.
In the example a hex value 0x83 from the Host is translated to ascii
character 'c'.

If identical ASCII values are defined for more than one ebcdic character,
the last will be valid, when translating from ASCII to ebcdic. If as an 
example ebcdic 0x50 should be translated to an ASCII space it is important 
to put the line

0x50 0x20

before 

0x40 0x20

Otherwise Users input when pressing the space bar will be wrong. A value of
0x40 should be expected.

Mocha TN3270 comes with 2 layouts:

  tn3270.ebc   : US layout (default)
  tn3270.dan   : Danish layout

See also 4.22, parameter ebcdic_file.

6.1 File tn3270.ebc
===================
Mocha TN3270 comes with an ASCII - EBCDIC layout as:

     0  1  2  3  4  5  6  7  8  9  A  B  C  D  E  F
  0 SP          SP  &  -                 {  }  \  0
  1                    /     a  j  ~     A  J     1
  2                          b  k  s     B  K  S  2
  3                          c  l  t     C  L  T  3
  4                          d  m  u     D  M  U  4 
  5                          e  n  v     E  N  V  5  
  6                          f  o  w     F  O  W  6 
  7                          g  p  x     G  P  X  7 
  8                          h  q  y     H  Q  Y  8
  9                       `  i  r  z     I  R  Z  9
  A                !   |  :
  B              . $   ,  #
  C              < .   %  @
  D              ( )   _  '
  E              + ;   >  =
  F              | -   ?  "
 
SP = space
Above EBCDIC value 0xd4 = 'M'

6.2 File tn3270.dan
===================
A Danish codepage has been included:

     0  1  2  3  4  5  6  7  8  9  A  B  C  D  E  F
  0 SP          SP  &  -                     \  0
  1                    /     a  j        A  J     1
  2                          b  k  s     B  K  S  2
  3                          c  l  t     C  L  T  3
  4                          d  m  u     D  M  U  4 
  5                          e  n  v     E  N  V  5  
  6                          f  o  w     F  O  W  6 
  7                          g  p  x     G  P  X  7 
  8                          h  q  y     H  Q  Y  8
  9                       `  i  r  z     I  R  Z  9
  A              #       :
  B              .    ,  
  C              < *   %  
  D              ( )   _  '
  E              + ;   >  =
  F              ! ^   ?  "
 

SP = space

7.0 License System
=================
The license system for Mocha TN3270 is very user friendly. The encrypted
parameter "license_key", together with parameter "license" gives a check for
legal use. Therefore it is not possible to change the company name in
"license", without ordering a new key from MochaSoft.

If parameter "license_key" is not given, the program will run in Demo mode, 
and display a banner in the title line. There will be no limitations on 
functionality.

8.0 Files
=========
Following files must exist together with the HTML page loading
Mocha TN3270

   tn3270.class
   tnnet.class
   tntimer.class
   tnpop.class
   tn3270exe.class (only for mode 1)
   tnvt.class
   tnvid.class
   keys
   tn3270.cfg (only for mode 1)
   tn3270.ebc (US ASCII - EBCDIC table)
   tn3270.dan (Danish ASCII - EBCDIC table)
